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ABOUT THIS CHAPTER 


This chapter describes the Dialog Manager, the part of the Toolbox that allows 
you to implement dialog boxes and the alert mechanism, two means of 
communication between the application and the end user. 


This chapter also describes the enhancements to the Dialog Manager for the 
Macintosh II. A new Dialog Manager routine now provides color dialog and item 
Support. The new resource types ‘dctb', ‘actb', and ‘ictb', which are auxiliary 
data structures to 'DITL', 'ALRT', and 'DLOG', allow color dialog boxes and 
alert boxes to be stored as resources. If the 'ALRT', 'DLOG', or 

'DITL' resources are missing, the Dialog Manager will gracefully return from the 
Alert, NoteAlert, CautionAlert, StopAlert, and GetNewDialog calls. 


You should already be familiar with: 


* resources, as discussed in the Resource Manager chapter 

¢ the basic concepts and structures behind QuickDraw, particularly 
rectangles, grafPorts, and pictures 

¢ the Toolbox Event Manager, the Window Manager, and the Control Manager 

e TextEdit, to understand editing text in dialog boxes 
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ABOUT THE DIALOG MANAGER 


The Dialog Manager is a tool for handling dialogs and alerts in a way that's 
consistent with the Macintosh User Interface Guidelines. 

A dialog box appears on the screen when a Macintosh application needs more 
information to carry out a command. As shown in Figure 1, it typically resembles 
a form on which the user checks boxes and fills in blanks. 
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Figure 1-A Typical Dialog Box 
Figure 1-A Typical Dialog Box 


By convention, a dialog box comes up slightly below the menu bar, is somewhat 
narrower than the screen, and is centered between the left and right edges of 
the screen. It may contain any or all of the following: 


e informative or instructional text 

e rectangles in which text may be entered (initially blank or 
containing default text that can be edited) 

« controls of any kind 

* graphics (icons or QuickDraw pictures) 

e anything else, as defined by the application 


The user provides the necessary information in the dialog box, such as by 
entering text or clicking a check box. There's usually a button labeled "OK" to 
tell the application to accept the information provided and perform the command, 
and a button labeled "Cancel" to cancel the command as though it had never been 
given (retracting all actions since its invocation). Some dialog boxes may use a 
more descriptive word than "OK"; for simplicity, this chapter will still refer 
to the button as the "OK button". There may even be more than one button that 
will perform the command, each in a different way. 


Most dialog boxes require the user to respond before doing anything else. 
Clicking a button to perform or cancel the command makes the box go away; 
clicking outside the dialog box only causes a beep from the Macintosh's speaker. 
This type is called a modal dialog box because it puts the user in the state or 
"mode" of being able to work only inside the dialog box. A modal dialog box 
usually has the same general appearance as shown in Figure 1 above. One of the 
buttons in the dialog box may be outlined boldly. Pressing the Return key or the 
Enter key has the same effect as clicking the outlined button or, if none, the 
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OK button; the particular button whose effect occurs is called the dialog's 
default button and is the preferred ("safest") button to use in the current 
situation. If there's no boldly outlined or OK button, pressing Return or Enter 
will by convention have no effect. 


Other dialog boxes do not require the user to respond before doing anything 
else; these are called modeless dialog boxes (see Figure 2). The user can, for 
example, do work in document windows on the desktop before clicking a button in 
the dialog box, and modeless dialog boxes can be set up to respond to the 
standard editing commands in the Edit menu. Clicking a button in a modeless 
dialog box will not make the box go away: The box will stay around so that the 
user can perform the command again. A Cancel button, if present, will simply 
stop the action currently being performed by the command; this would be useful 
for long printing or searching operations, for example. 


Change To: |Spinside Macintosh 


[] Whole Word |] Match Upper/Lowercase 


Start Search Change all 


Figure 2-4 Modeless Dialog Box 
Figure 2—-A Modeless Dialog Box 


As shown in Figure 2, a modeless dialog box looks like a document window. It can 
be moved, made inactive and active again, or closed like any document window. 
When you're done with the command and want the box to go away, you can click its 
close box or choose Close from the File menu when it's the active window. 


Dialog boxes may in fact require no response at all. For example, while an 
application is performing a time-consuming process, it can display a dialog box 
that contains only a message telling what it's doing; then, when the process is 
complete, it can simply remove the dialog box. 


The alert mechanism provides applications with a means of reporting errors or 
giving warnings. An alert box is similar to a modal dialog box, but it appears 
only when something has gone wrong or must be brought to the user's attention. 
Its conventional placement is slightly farther below the menu bar than a dialog 
box. To assist the user who isn't sure how to proceed when an alert box appears, 
the preferred button to use in the current situation is outlined boldly so it 
stands out from the other buttons in the alert box (see Figure 3). The outlined 
button is also the alert's default button; if the user presses the Return key or 
the Enter key, the effect is the same as clicking this button. 
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Figure 3-A Typical Alert Bor 
Figure 3—A Typical Alert Box 


There are three standard kinds of alerts—Stop, Note, and Caution—each indicated 
by a particular icon in the top left corner of the alert box. Figure 3 
illustrates a Caution alert. The icons identifying Stop and Note alerts are 
Similar; instead of a question mark, they show an exclamation point and an 
asterisk, respectively. Other alerts can have anything in the the top left 
corner, including blank space if desired. 


The alert mechanism also provides another type of signal: Sound from the 
Macintosh's speaker. The application can base its response on the number of 
consecutive times an alert occurs; the first time, it might simply beep, and 
thereafter it may present an alert box. The sound isn't limited to a single beep 
but may be any sequence of tones, and may occur either alone or along with an 
alert box. AS an error is repeated, there can also be a change in which button 
is the default button (perhaps from OK to Cancel). You can specify different 
responses for up to four occurrences of the same alert. 


With Dialog Manager routines, you can create dialog boxes or invoke alerts. The 
Dialog Manager gets most of the descriptive information about the dialogs and 
alerts from resources in a resource file. The Dialog Manager calls the Resource 
Manager to read what it needs from the resource file into memory as necessary. 
In some cases you can modify the information after it's been read into memory. 


Four routines—HideDItem, ShowDItem, FindDItem, and UpdtDialog—have been added to 
the Dialog Manager. 


Advanced programmers: The standard filterProc function called by 
ModalDialog now returns 1 in itemHit and a 
function result of TRUE only if the first item 
is enabled. 


Automatic scrolling is supported in editText items. 
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DIALOG AND ALERT WINDOWS 


A dialog box appears in a dialog window. When you call a Dialog Manager routine 

to create a dialog, you supply the same information as when you create a window 

with a Window Manager routine. For example, you supply the window definition ID, 
which determines how the window looks and behaves, and a rectangle that becomes 

the portRect of the window's grafPort. You specify the window's plane (which, by 
convention, should initially be the frontmost) and whether the window is visible 
or invisible. The dialog window is created as specified. 


You can manipulate a dialog window just like any other window with Window 
Manager or QuickDraw routines, showing it, hiding it, moving it, changing its 
Size or plane, or whatever— all, of course, in conformance with the Macintosh 
User Interface Guidelines. The Dialog Manager observes the clipping region of 
the dialog window's grafPort, so if you want clipping to occur, you can set this 
region with a QuickDraw routine. 


Similarly, an alert box appears in an alert window. You don't have the same 
flexibility in defining and manipulating an alert window, however. The Dialog 
Manager chooses the window definition ID, so that all alert windows will have 
the standard appearance and behavior. The size and location of the box are 
Supplied as part of the definition of the alert and are not easily changed. You 
don't specify the alert window's plane; it always comes up in front of all other 
windows. Since an alert box requires the user to respond before doing anything 
else, and the response makes the box go away, the application doesn't do any 
manipulation of the alert window. 


Figure 4 illustrates a document window, dialog window, and alert window, all 
overlapping on the desktop. 
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Figure 4—Dialog and Alert Windows 
Figure 4—Dialog and Alert Windows 


@ SpInside Macintosh ¢ Version 1.0 * November 1989 * Apple Computer 
THE DIALOG MANAGER « 8 of 53 


DIALOGS, ALERTS, AND RESOURCES 


To create a dialog, the Dialog Manager needs the same information about the 
dialog window as the Window Manager needs when it creates a new window: The 
window definition ID along with other information specific to this window. The 
Dialog Manager also needs to know what items the dialog box contains. You can 
store the needed information as a resource in a resource file and pass the 
resource ID to a function that will create the dialog. This type of resource, 
which is called a dialog template, is analogous to a window template, and the 
function, GetNewDialog, is similar to the Window Manager function GetNewWindow. 
The Dialog Manager calls the Resource Manager to read the dialog template from 
the resource file. It then incorporates the information in the template into a 
dialog data structure in memory, called a dialog record. 


Similarly, the data that the Dialog Manager needs to create an alert is stored 
in an alert template in a resource file. The various routines for invoking 
alerts require the resource ID of the alert template as a parameter. 


The information about all the items (text, controls, or graphics) in a dialog or 
alert box is stored in an item list in a resource file. The resource ID of the 
item list is included in the dialog or alert template. The item list in turn 
contains the resource IDs of any icons or QuickDraw pictures in the dialog or 
alert box, and possibly the resource IDs of control templates for controls in 
the box. After calling the Resource Manager to read a dialog or alert template 
into memory, the Dialog Manager calls it again to read in the item list. It then 
makes a copy of the item list and uses that copy; for this reason, item lists 
should always be purgeable resources. Finally, the Dialog Manager calls the 
Resource Manager to read in any individual items as necessary. 


If desired, the application can gain some additional flexibility by calling the 
Resource Manager directly to read templates, item lists, or items from a 
resource file. For example, you can read in a dialog or alert template directly 
and modify some of the information in it before calling the routine to create 
the dialog or alert. Or, as an alternative to using a dialog template, you can 
read in a dialog's item list directly and then pass a handle to it along with 
other information to a function that will create the dialog (NewDialog, 
analogous to the Window Manager function NewWindow) . 


Note: The use of dialog templates is recommended wherever possible; like 
window templates, they isolate descriptive information from your 
application code for ease of modification or translation to other 
languages. 
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COLOR ALERT AND DIALOG RESOURCES 


You don't have to call any new routines to create color alert or dialog boxes. 
Additional resources of types ‘actb', ‘dctb', and ‘ictb' complement the existing 
'ALRT', 'DLOG', and 'DITL' resources, and provide all the information needed to 
color dialog windows, controls, and text. 


To create a dialog or alert box, the Dialog Manager needs the same information 
about the box as the Window Manager needs when it creates a new window. The 
structure of dialog color tables and alert color tables is similar to the window 
color table described in the Window Manager chapter, as shown in 

Figure 5. 


Value ic always 0 


Value is -1 for default window colors 


Partldentifier FartRGE 
value supplied by constants walue supplied by application 
[see Window Manager chapter] 


Figure 5-Color Table for Dialogs and Alerts 
Figure 5—Color Table for Dialogs and Alerts. 


The calls Alert, CautionAlert, StopAlert, and NoteAlert look for a resource of 
type ‘actb' with the same resource ID as the alert. GetNewDialog looks for a 
resource of type ‘'dctb' with the same resource ID as the dialog. These 
resources contain color tables identical to the 'wctb' color tables described in 
the Window Manager GetNewCWindow call. If an ‘actb' or 'dctb' resource is 
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present, then the window created will be a cGrafPort, created with a NewCWindow 
call. If the ctSize field of a 'dctb' or ‘actb' resource is —1, the default 
window colors will be used. 


To include a color icon in a dialog box, add a resource of type ‘cicn' with the 
same resource ID as an old-style icon. The Dialog Manager will then access the 
icon with the QuickDraw routine GetCIcon. 


To include a version 2 picture in a dialog, create a color table for the dialog 
to cause the dialog to use a cGrafPort. See the Color QuickDraw chapter for more 
information on the use of color pictures. 


To color controls in a dialog, or to change the color, style, font, or size of 
text within a dialog, include an 'ictb' resource as described in the following 
section. 


Color table resources ‘actb' and 'dctb' are treated the same as 'ALRT' resources 
and 'DLOG' resources. The ‘ictb' resource is handled just like the 

'‘DITL' resource. These resources are preloaded and made nonpurgeable by 
CouldAlert and CouldDialog, and their original purge state is restored by 
FreeAlert and FreeDialog. 
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ITEM LISTS IN MEMORY 


This section discusses the contents of an item list once it's been read into 
memory from a resource file and the Dialog Manager has set it up as necessary to 
be able to work with it. 


An item list in memory contains the following information for each item: 


« The type of item. This includes not only whether the item is a control, 
text, or whatever, but also whether the Dialog Manager should return to 
the application when the item is clicked. 

¢ A handle to the item or, for special application-defined items, a 
pointer to a procedure that draws the item. 

¢ A display rectangle, which determines the location of the item within 
the dialog or alert box. 


These are discussed below along with item numbers, which identify particular 
items in the item list. 


There's a Dialog Manager procedure that, given a pointer to a dialog record and 
an item number, sets or returns that item's type, handle (or procedure pointer), 
and display rectangle. 


Item Types 
The item type is specified by a predefined constant or combination of constants, 
as listed below. Figure 6 illustrates some of these item types. 


ctrltem statText editText etrltem 
+ radCtrl + itemDicable +itemDisable +btnCtrl 
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Figure 6-Item Types 
Figure 6—Item Types 
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Item type Meaning 


ctrlitem+btnCtrl A standard button control. 
ctrliItem+chkCtrl A standard check box control. 


ctrlItem+radCtrl A standard radio button control. 

ctrlItem+resCtrl A control defined in a control template 
in a resource file. 

statText Static text; text that cannot be edited. 

editText (Dialogs only) Text that can be edited; 


the Dialog Manager accepts text typed by 
the user and allows editing. 


iconItem An icon. 
picItem A QuickDraw picture. 
userItem (Dialogs only) An application-defined item, 

such as a picture whose appearance changes. 
itemDisable+<any The item is disabled (the Dialog Manager doesn't 
of the above> report events involving this item). 


The text of an editText item may initially be either default text or empty. Text 
entry and editing is handled in the conventional way, as in TextEdit—in fact, 
the Dialog Manager calls TextEdit to handle it: 


e Clicking in the item displays a blinking vertical bar, indicating 
an insertion point where text may be entered. 

« Dragging over text in the item selects that text, and double-clicking 
selects a word; the selection is highlighted and then replaced by 
what the user types. 

e Clicking or dragging while holding down the Shift key extends or 
shortens the current selection. 

e The Backspace key deletes the current selection or the character 
preceding the insertion point. 


The Tab key advances to the next editText item in the item list, wrapping around 
to the first if there aren't any more. In an alert box or a modal dialog box 
(regardless of whether it contains an editText item), the Return key or Enter 
key has the same effect as clicking the default button; for alerts, the default 
button is identified in the alert template, whereas for modal dialogs it's 
always the first item in the item list. 


If itemDisable is specified for an item, the Dialog Manager doesn't let the 
application know about events involving that item. For example, you may not have 
to be informed every time the user types a character or clicks in an editText 
item, but may only need to look at the text when the OK button is clicked. In 
this case, the editText item would be disabled. Standard buttons and check boxes 
should always be enabled, so your application will know when they've been 
clicked. 


Warning: Don't confuse disabling a control with making one "inactive" 
with the Control Manager procedure HiliteControl: When you 
want a control not to respond at all to being clicked, you 
make it inactive. An inactive control is highlighted to show 
that it's inactive, while disabling a control doesn't affect 
its appearance. 
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Item Handle or Procedure Pointer 


The item list contains the following information for the various types of items: 


Item type Contents 

any ctrlitem A control handle 

statText A handle to the text 
editText A handle to the current text 
iconItem A handle to the icon 

picItem A picture handle 

userItem A procedure pointer 


The procedure for a userItem draws the item; for example, if the item is a 
clock, it will draw the clock with the current time displayed. When this 
procedure is called, the current port will have been set by the Dialog Manager 
to the dialog window's grafPort. The procedure must have two parameters, a 
window pointer and an item number. For example, this is how it would be declared 
if it were named MyItem: 


PROCEDURE MyItem (theWindow: WindowPtr; itemNo: INTEGER); 


TheWindow is a pointer to the dialog window; in case the procedure draws in more 
than one dialog window, this parameter tells it which one to draw in. ItemNo is 

the item number; in case the procedure draws more than one item, this parameter 

tells it which one to draw. 


Display Rectangle 
Each item in the item list is displayed within its display rectangle: 


¢ For controls, the display rectangle becomes the control's 
enclosing rectangle. 

¢ For an editText item, it becomes TextEdit's destination rectangle 
and view rectangle. Word wraparound occurs, and the text is clipped 
if there's more than will fit in the rectangle. In addition, the 
Dialog Manager uses the QuickDraw procedure FrameRect to draw a 
rectangle three pixels outside the display rectangle. 

e StatText items are displayed in exactly the same way as editText 
items, except that a rectangle isn't drawn outside the display rectangle. 

e Icons and QuickDraw pictures are scaled to fit the display rectangle. 
For pictures, the Window Manager calls the QuickDraw procedure 
DrawPicture and passes it the display rectangle. 

e If the procedure for a userItem draws outside the item's display 
rectangle, the drawing is clipped to the display rectangle. 


Note: Clicking anywhere within the display rectangle is considered a 
click in that item. If display rectangles overlap, a click in 
the overlapping area is considered a click in whichever item 
comes first in the item list. 


By giving an item a display rectangle that's off the screen, you can make the 
item invisible. This might be useful, for example, if your application needs to 
display a number of dialog boxes that are similar except that one item is 
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missing or different in some of them. You can use a single dialog box in which 
the item or items that aren't currently relevant are invisible. To remove an 
item or make one reappear, you just change its display rectangle (and call the 
Window Manager procedure InvalRect to accumulate the changed area into the 
dialog window's update region). The QuickDraw procedure OffsetRect is convenient 
for moving an item off the screen and then on again later. Note the following, 
however: 


¢ You shouldn't make an editText item invisible, because it may cause 
strange things to happen. If one of several editText items is invisible, 
for example, pressing the Tab key may make the insertion point disappear. 
However, if you do make this type of item invisible, remember that the 
changed area includes the rectangle that's three pixels outside the 
item's display rectangle. 

e The rectangle for a statText item must always be at least as wide as 
the first character of the text; a good rule of thumb is to make it 
at least 20 pixels wide. 

« To change text in a statText item, it's easier to use the Dialog 
Manager procedure ParamText (as described later in the "Dialog Manager 
Routines" section). 


Item Numbers 


Each item in an item list is identified by an item number, which is simply the 
index of the item in the list (starting from 1). By convention, the first item 
in an alert's item list should be the OK button (or, if none, then one of the 
buttons that will perform the command) and the second item should be the Cancel 
button. The Dialog Manager provides predefined constants equal to the item 
numbers for OK and Cancel: 


CONST ok 
cancel 


1 
2; 
In a modal dialog's item list, the first item is assumed to be the dialog's 
default button; if the user presses the Return key or Enter key, the Dialog 
Manager normally returns item number 1, just as when that item is actually 
clicked. To conform to the Macintosh User Interface Guidelines, the application 
should boldly outline the dialog's default button if it isn't the OK button. The 
best way to do this is with a userItem. To allow for changes in the default 
button's size or location, the userItem should identify which button to outline 
by its item number and then use that number to get the button's display 
rectangle. The following QuickDraw calls will outline the rectangle in the 
standard way: 


PenSize(3,3); 
InsetRect (displayRect ,—4,-4); 
FrameRoundRect (displayRect,16,16) 


Warning: If the first item in a modal dialog's item list isn't an OK 
button and you don't boldly outline it, you should set up the 
dialog to ignore Return and Enter. To learn how to do this, 
see ModalDialog under "Handling Dialog Events" in the "Dialog 
Manager Routines" section. 
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COLOR DIALOG ITEM LISTS 


This section discusses the contents of an item list after it's been read into 
memory from a resource file. If a resource of type ‘ictb' is present with the 
same resource ID as the 'DITL' resource (in addition to the presence of the 
‘'dctb' or ‘actb' resources), then the statText, editText, and control items in 
the dialog or alert boxes are drawn using the colors and text styles indicated 
by the item color table record contained in the resource. 


Note: Neither the display device nor the dialog box needs to be in color, 
but a dialog or alert color table must exist to include an item color 
table (even if the item color table only describes statText and editText 
style changes and has no actual color information). 


Figure 7 shows how a dialog color table stores item color table records. 
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Figure 7-Color Table for Dialogs and Alerts 
Figure 7—Color Table for Dialogs and Alerts. 


The record starts with an array of two-word entries for each item in the 
matching dialog item list. The first word (itemCData) is the length of the entry 
if the item is a control, or it is a word of flags if the item is an editText or 
statText item. The second word (itemCOffset) is an offset from the beginning of 
the record to the color item entry. This color record is used only for controls 
and text; icons and pictures have a different method of describing associated 
colors. Set the itemCData and itemCOffset fields to zero for controls or text 
without colors or font changes. 


If the item is an editText or statText item, the bits in the itemCData field 
determine which fields of the text style record to use; these bit equates are 
listed in the following table. 
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Bit Meaning 

0 Change the font family 

1 Change the font face 

2 Change the font size 

3 Change the font forecolor 


4 Add the font size 

13 Change the font backcolor 

14 Change the font mode 

15 The font field is an offset to the name. 


Note: Multiple text items can share the same font name. 

The itemCData field for text items contains a superset of the flags passed as 
the mode word to the TextEdit routine TESetStyle. The constants defined for 
that routine include: 


CONST 


{ Constants for TextEdit and dialog boxes } 


TEdoFont = 1; {set font (family) number} 
TEdoFace = 20 {set character style} 
TEdoSize = 4; {set type size} 

TEdoColor = 8; {set foreground color} 
TEdoALl =15% {set all attributes} 
TEaddSize = 16; {adjust type size} 


{ Constants for dialog boxes only } 


doBColor = 8192; {set backgound color} 
doMode = 16384; {set txMode} 
doFontName = 32768; {set txFont from name} 


The text style record indicated by itemCOffset must be 20 bytes long, as shown 
in Figure 7. Multiple statText and editText items can use the same text style 
record. To display text in the standard font, color, size, and style, set the 
itemCData and itemCOffset to zero. Allocate space for all fields in the style 
table, even if they are not used. Even if only the first few items of the dialog 
box have color style information, there must be room for all of the items 
actually in the box (with the data and offset words of the unused entries set to 
zero). 


For controls, the colors are described by a color table identical to the 
contents of a ‘'cctb' resource used by a GetNewCControl call. Multiple controls 
can use the same color table. To display a control in the default colors, set 
the itemCData and itemCOffset fields to zero. The length of the control color 
table should be the header size of eight bytes plus the eight-byte ColorSpec 
record for each entry in the color table. 


The doFontName array is optional. However, it's important to point to the name 
of the font instead of just including the font number. Fonts may be renumbered 
by font installers like the Font/DA Mover as the fonts are moved, so it is 
safest to rely on getting the right font by referring to the name. 
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Figure 9-Sample Dialog with Color Dialog Items (B/W Version). 
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USING COLOR DIALOGS AND ALERTS 


The dialog box shown in Figure 8 contains 12 different dialog items. Some of 
these items—the OK and Cancel buttons, the radio buttons and the check box, and 
the editText and statText items—contain color information. The table shown in 
the figure contains the hexadecimal description of the dialog items. PicItems, 
iconItems, resCtrls and userItems should have zeroed entries for both fields. 
All items in the dialog should have a field, whether or not the item uses the 
new features. 


Your application can create a dialog or alert, with color dialog items, within a 
resource file, and then use the GetNewDialog routine with the dialog's resource 
ID. You can also use the NewCDialog routine to create a dialog or alert within 
an application, passing a handle to the dialog's item list. 
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DIALOG RECORDS 


To create a dialog, you pass information to the Dialog Manager in a dialog 
template and in individual parameters, or only in parameters; in either case, 
the Dialog Manager incorporates the information into a dialog record. The dialog 
record contains the window record for the dialog window, a handle to the 
dialog's item list, and some additional fields. The Dialog Manager creates the 
dialog window by calling the Window Manager function NewWindow and then setting 
the window class in the window record to indicate that it's a dialog window. The 
routine that creates the dialog returns a pointer to the dialog record, which 
you use thereafter to refer to the dialog in Dialog Manager routines or even in 
Window Manager or QuickDraw routines (see "Dialog Pointers" below). The Dialog 
Manager provides routines for handling events in the dialog window and disposing 
of the dialog when you're done. 


The data type for a dialog record is called DialogRecord. You can do all the 
necessary operations on a dialog without accessing the fields of the dialog 
record directly; for advanced programmers, however, the exact structure of a 
dialog record is given under "The DialogRecord Data Type" below. 


Dialog Pointers 


There are two types of dialog pointer, DialogPtr and DialogPeek, analogous to 
the window pointer types WindowPtr and WindowPeek. Most programmers will only 
need to use DialogPtr. 


The Dialog Manager defines the following type of dialog pointer: 
TYPE DialogPtr = WindowPtr; 


It can do this because the first field of a dialog record contains the window 
record for the dialog window. This type of pointer can be used to access fields 
of the window record or can be passed to Window Manager routines that expect 
window pointers as parameters. Since the WindowPtr data type is itself defined 
as GrafPtr, this type of dialog pointer can also be used to access fields of the 
dialog window's grafPort or passed to QuickDraw routines that expect pointers to 
grafPorts as parameters. 


For programmers who want to access dialog record fields beyond the window 
record, the Dialog Manager also defines the following type of dialog pointer: 


TYPE DialogPeek = “DialogRecord; 
Assembly-language note: From assembly language, of course, there's no 


type checking on pointers, and the two types 
of pointer are equal. 


The DialogRecord Data Type 
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For those who want to know more about the data structure of a dialog record, the 
exact structure is given here. 


TYPE DialogRecord = RECORD 


window: WindowRecord; {dialog window} 

items: Handle; {item list} 

textH: TEHandle; {current editText item} 

editField: INTEGER; {editText item number minus 1} 

editOpen: INTEGER; {used internally} 

aDefitem: INTEGER {default button item number} 
END; 


The window field contains the window record for the dialog window. The items 
field contains a handle to the item list used for the dialog. (Remember that 
after reading an item list from a resource file, the Dialog Manager makes a copy 
of it and uses that copy.) 


Note: To get or change information about an item in a dialog, you pass the 
dialog pointer and the item number to a Dialog Manager procedure. 
You'll never access information directly through the handle to the 
item list. 


The Dialog Manager uses the next three fields when there are one or more 
editText items in the dialog. If there's more than one such item, these fields 
apply to the one that currently is selected or displays the insertion point. The 
textH field contains the handle to the edit record used by TextEdit. EditField 
is 1 less than the item number of the current editText item, or —1 if there's no 
editText item in the dialog. The editOpen field is used internally by the Dialog 
Manager. 


Note: Actually, a single edit record is shared by all editText items; any 
changes you make to it will apply to all such items. See the TextEdit 
chapter for details about what kinds of changes you can make. 


The aDefItem field is used for modal dialogs and alerts, which are treated 
internally as special modal dialogs. It contains the item number of the default 
button. The default button for a modal dialog is the first item in the item 
list, so this field contains 1 for modal dialogs. The default button for an 
alert is specified in the alert template; see the following section for more 
information. 


ALERTS 


When you call a Dialog Manager routine to invoke an alert, you pass it the 
resource ID of the alert template, which contains the following: 


« A rectangle, given in global coordinates, which determines the alert 
window's size and location. It becomes the portRect of the window's 
grafPort. To allow for the menu bar and the border around the portRect, 
the top coordinate of the rectangle should be at least 25 points below 
the top of the screen. 

« The resource ID of the item list for the alert. 
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¢ Information about exactly what should happen at each stage of the alert. 


Every alert has four stages, corresponding to consecutive occurrences of the 
alert: The first three stages correspond to the first three occurrences, while 
the fourth stage includes the fourth occurrence and any beyond the fourth. (The 
Dialog Manager compares the current alert's resource ID to the last alert's 
resource ID to determine whether it's the same alert.) The actions for each 
stage are specified by the following three pieces of information: 


e which is the default button—the OK button (or, if none, a button that 
will perform the command) or the Cancel button 

¢ whether the alert box is to be drawn 

¢ which of four sounds should be emitted at this stage of the alert 


The alert sounds are determined by a sound procedure that emits one of up to 
four tones or sequences of tones. The sound procedure has one parameter, an 

integer from 0 to 3; it can emit any sound for each of these numbers, which 

identify the sounds in the alert template. For example, you might declare a 

sound procedure named MySound as follows: 


PROCEDURE MySound (soundNo: INTEGER); 


If you don't write your own sound procedure, the Dialog Manager uses the 
standard one: Sound number 0 represents no sound and sound numbers 1 through 3 
represent the corresponding number of short beeps, each of the same pitch and 
duration. The volume of each beep depends on the current speaker volume setting, 
which the user can adjust with the Control Panel desk accessory. If the user has 
set the speaker volume to 0, the menu bar will blink in place of each beep. 


For example, if the second stage of an alert is to cause a beep and no alert 
box, you can just specify the following for that stage in the alert template: 
Don't draw the alert box, and use sound number 1. If instead you want, say, two 
successive beeps of different pitch, you need to write a procedure that will 
emit that sound for a particular sound number, and specify that number in the 
alert template. The Macintosh Operating System includes routines for emitting 
sound; see the Sound Driver chapter, and also the simple SysBeep procedure in 
the Operating System Utilties chapter. (The standard sound procedure calls 
SysBeep. ) 


Note: When the Dialog Manager detects a click outside an alert box or a 
modal dialog box, it emits sound number 1; thus, for consistency 
with the Macintosh User Interface Guidelines, sound number 1 should 
always be a single beep. 


Internally, alerts are treated as special modal dialogs. The alert routine 
creates the alert window by calling NewDialog. The Dialog Manager works from the 
dialog record created by NewDialog, just as when it operates on a dialog window, 
but it disposes of the window before returning to the application. Normally your 
application won't access the dialog record for an alert; however, there is a way 
that this can happen: For any alert, you can specify a procedure that will be 
executed repeatedly during the alert, and this procedure may access the dialog 
record. For details, see the alert routines under 

"Invoking Alerts" in the "Dialog Manager Routines" section. 
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USING THE DIALOG MANAGER 


Before using the Dialog Manager, you must initialize QuickDraw, the Font 
Manager, the Window Manager, the Menu Manager, and TextEdit, in that order. The 
first Dialog Manager routine to call is InitDialogs, which initializes the 
Dialog Manager. If you want the font in your dialog and alert windows to be 
other than the system font, call SetDAFont to change the font. 


Where appropriate in your program, call NewDialog or GetNewDialog to create any 
dialogs you need. Usually you'll call GetNewDialog, which takes descriptive 
information about the dialog from a dialog template in a resource file. You can 
instead pass the information in individual parameters to NewDialog. In either 
case, you can supply a pointer to the storage for the dialog record or let it be 
allocated by the Dialog Manager. When you no longer need a dialog, you'll 
usually call CloseDialog if you supplied the storage, or DisposDialog if not. 


In most cases, you probably won't have to make any changes to the dialogs from 
the way they're defined in the resource file. However, if you should want to 
modify an item in a dialog, you can call GetDItem to get the information about 
the item and SetDItem to change it. In particular, SetDItem is the routine to 
use for installing a userItem. In some cases it may be appropriate to call some 
other Toolbox routine to change the item; for example, to change or move a 
control in a dialog, you would get its handle from GetDItem and then call the 
appropriate Control Manager routine. There are also two procedures specifically 
for accessing or setting the content of a text item in a dialog box: GetIText 
and SetIText. 


To handle events in a modal dialog, just call the ModalDialog procedure after 
putting up the dialog box. If your application includes any modeless dialog 
boxes, you'll pass events to IsDialogEvent to learn whether they need to be 
handled as part of a dialog, and then usually call DialogSelect if so. Before 
calling DialogSelect, however, you should check whether the user has given the 
keyboard equivalent of a command, and you may want to check for other special 
cases, depending on your application. You can support the use of the standard 
editing commands in a modeless dialog's editText items with DlgCut, DlgCopy, 
DlgPaste, and DlgDelete. 


A dialog box that contains editText items normally comes up with the insertion 
point in the first such item in its item list. You may instead want to bring up 
a dialog box with text selected in an editText item, or to cause an insertion 
point or text selection to reappear after the user has made an error in entering 
text. For example, the user who accidentally types nonnumeric input when a 
number is required can be given the opportunity to type the entry again. The 
SelIText procedure makes this possible. 


For alerts, if you want other sounds besides the standard ones (up to three 
short beeps), write your own sound procedure and call ErrorSound to make it the 
current sound procedure. To invoke a particular alert, call one of the alert 
routines: StopAlert, NoteAlert, or CautionAlert for one of the standard kinds 
of alert, or Alert for an alert defined to have something other than a standard 
icon (or nothing at all) in its top left corner. 
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If you're going to invoke a dialog or alert when the resource file might not be 
accessible, first call CouldDialog or CouldAlert, which will make the dialog or 
alert template and related resources unpurgeable. You can later make them 
purgeable again by calling FreeDialog or FreeAlert. 


Finally, you can substitute text in statText items with text that you specify in 
the ParamText procedure. This means, for example, that a document name supplied 
by the user can appear in an error message. 
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DIALOG MANAGER ROUTINES 


Initialization 
PROCEDURE InitDialogs (resumeProc: ProcPtr); 


Call InitDialogs once before all other Dialog Manager routines, to initialize 
the Dialog Manager. InitDialogs does the following initialization: 


e It saves the pointer passed in resumeProc, if any, for access by the 
System Error Handler in case a fatal system error occurs. ResumeProc 
can be a pointer to a resume procedure, as described in the System 
Error Handler chapter, or NIL if no such procedure is desired. 


Assembly-language note: InitDialogs stores the address of the resume 
procedure in a global variable named ResumeProc. 


¢ It installs the standard sound procedure. 
e It passes empty strings to ParamText. 


PROCEDURE ErrorSound (soundProc: ProcPtr); 


ErrorSound sets the sound procedure for alerts to the procedure pointed to by 
soundProc; if you don't call ErrorSound, the Dialog Manager uses the standard 
sound procedure. (For details, see the "Alerts" section.) If you pass NIL for 
soundProc, there will be no sound (or menu bar blinking) at all. 


Assembly-language note: The address of the sound procedure being used is 
stored in the global variable DABeeper. 


PROCEDURE SetDAFont (fontNum: INTEGER); [Not in ROM] 


For subsequently created dialogs and alerts, SetDAFont causes the font of the 
dialog or alert window's grafPort to be set to the font having the specified 
font number. If you don't call this procedure, the system font is used. 
SetDAFont affects statText and editText items but not titles of controls, which 
are always in the system font. 


Assembly-language note: Assembly-language programmers can simply set 
the global variable DlgFont to the desired font number. 


Creating and Disposing of Dialogs 


FUNCTION NewDialog (dStorage: Ptr; boundsRect: Rect; title: Str255; 
visible: BOOLEAN; procID: INTEGER; behind: WindowPtr; 
goAwayFlag: BOOLEAN; refCon: LONGINT; 
items: Handle) : DialogPtr; 


NewDialog creates a dialog as specified by its parameters and returns a pointer 
to the new dialog. The first eight parameters (dStorage through refCon) are 
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passed to the Window Manager function NewWindow, which creates the dialog 
window; the meanings of these parameters are summarized below. The items 
parameter is a handle to the dialog's item list. You can get the items handle by 
calling the Resource Manager to read the item list from the resource file into 
memory. 


Note: Advanced programmers can create their own item lists in memory rather 
than have them read from a resource file. The exact format is given 
later under "Formats of Resources for Dialogs and Alerts". 


DStorage is analogous to the wStorage parameter of NewWindow; it's a pointer to 
the storage to use for the dialog record. If you pass NIL for dStorage, the 
dialog record will be allocated in the heap (which, in the case of modeless 
dialogs, may cause the heap to become fragmented). 


BoundsRect, a rectangle given in global coordinates, determines the dialog 
window's size and location. It becomes the portRect of the window's grafPort. 
Remember that the top coordinate of this rectangle should be at least 25 points 
below the top of the screen for a modal dialog, to allow for the menu bar and 
the border around the portRect, and at least 40 points below the top of the 
screen for a modeless dialog, to allow for the menu bar and the window's title 
bar. 


Title is the title of a modeless dialog box; pass the empty string for modal 
dialogs. 


If the visible parameter is TRUE, the dialog window is drawn on the screen. If 
it's FALSE, the window is initially invisible and may later be shown with a call 
to the Window Manager procedure ShowWindow. 


Note: NewDialog generates an update event for the entire window contents, 
so the items aren't drawn immediately, with the exception of controls. 
The Dialog Manager calls the Control Manager to draw controls, and the 
Control Manager draws them immediately rather than via the standard 
update mechanism. Because of this, the Dialog Manager calls the Window 
Manager procedure ValidRect for the enclosing rectangle of each control, 
so the controls won't be drawn twice. If you find that the other items 
aren't being drawn soon enough after the controls, try making the 
window invisible initially and then calling ShowWindow to show it. 


ProcID is the window definition ID, which leads to the window definition 
function for this type of window. The window definition IDs for the standard 
types of dialog window are dBoxProc for the modal type and documentProc for the 
modeless type. 


The behind parameter specifies the window behind which the dialog window is to 
be placed on the desktop. Pass POINTER(-—1) to bring up the dialog window in 
front of all other windows. 


GoAwayFlag applies to modeless dialog boxes; if it's TRUE, the dialog window has 
a close box in its title bar when the window is active. 


RefCon is the dialog window's reference value, which the application may store 
into and access for any purpose. 
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NewDialog sets the font of the dialog window's grafPort to the system font or, 
if you previously called SetDAFont, to the specified font. It also sets the 
window class in the window record to dialogKind. 


FUNCTION NewCDialog (dStorage: Ptr; boundsRect: Rect; title: Str255; 
visible: BOOLEAN; procID: INTEGER; behind: WindowPtr; 
goAwayFlag: BOOLEAN; refCon: LONGINT; 
items: Handle) : CDialogPtr; 


A new Dialog Manager routine has been added to support color dialogs: 
NewCDialog. Its parameters are identical to NewDialog, except that a cGrafPort 
is allocated through a NewCWindow call instead of a call to NewWindow. 


NewCDialog creates a dialog box as specified by its parameters and returns a 
cDialogPtr to the new dialog. The first eight parameters (dStorage through 
refCon) are passed to the Window Manager function NewCWindow, which creates the 
dialog window. The items parameter is a handle to the dialog's item list. You 
can get the items handle by calling the Resource Manager to read the item list 
from the resource file into memory. 


After calling NewCDialog, you can use SetWinColor to add a color table to the 
dialog. This creates an auxiliary window record (auxWinRec) for the dialog 
window. You can access this record with the GetAuxWin routine. The dialogCItem 
handle within the auxWinRec points to the dialog item color table. 


If the dialog's content color isn't white, it's a good idea to call NewCDialog 
with the visible flag set to FALSE. After the color table and color item list 
are installed, use ShowWindow to display the dialog if the dialog is the 
frontmost window. If the dialog is not in front, use ShowHide to display the 
dialog. 


FUNCTION GetNewDialog (dialogID: INTEGER; dStorage: Ptr; 
behind: WindowPtr) : DialogPtr; 


Like NewDialog (above), GetNewDialog creates a dialog as specified by its 
parameters and returns a pointer to the new dialog. Instead of having the 
parameters boundsRect, title, visible, procID, goAwayFlag, and refCon, 
GetNewDialog has a single dialogID parameter, where dialogID is the resource ID 
of a dialog template that supplies the same information as those parameters. The 
dialog template also contains the resource ID of the dialog's item list. After 
calling the Resource Manager to read the item list into memory (if it's not 
already in memory), GetNewDialog makes a copy of the item list and uses that 
copy; thus you may have multiple independent dialogs whose items have the same 
types, locations, and initial contents. The dStorage and behind parameters of 
GetNewDialog have the same meaning as in NewDialog. 


Warning: If either the dialog template resource or the item list 
resource can't be read, the function result is undefined. 


Note: GetNewDialog doesn't release the memory occupied by the resources. 
The GetNewDialog routine will attempt to load a ‘dctb' resource and returns a 


pointer to a color grafPort if the resource exists. If no 'dctb' resource is 
present, GetNewDialog returns a pointer to an old grafPort. 
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The dialog color table is copied before it is passed to SetWinSize unless its 
ctSize field is equal to -—1, indicating that the default window colors are to be 
used instead. The copy is made so that the color table resource can be purged 
without affecting the dialog. 


The color dialog item list resource is duplicated as well, so it can be 
purgeable. 


PROCEDURE CloseDialog (theDialog: DialogPtr); 


CloseDialog removes theDialog's window from the screen and deletes it from the 
window list, just as when the Window Manager procedure CloseWindow is called. It 
releases the memory occupied by the following: 


¢ The data structures associated with the dialog window (such as the 
window's structure, content, and update regions). 

« All the items in the dialog (except for pictures and icons, which 
might be shared resources), and any data structures associated with 
them. For example, it would dispose of the region occupied by the 
thumb of a scroll bar, or a similar region for some other control 
in the dialog. 


CloseDialog does not dispose of the dialog record or the item list. Figure 10 
illustrates the effect of CloseDialog (and DisposDialog, described below). 
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CloseLDislog releases only those areas marked & 
DisposeDislog releases the areas marked & 
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dialog record item list 
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Figure 10-CloseDialog and DisposDialog 
Figure 10-—CloseDialog and DisposDialog 


Call CloseDialog when you're done with a dialog if you supplied NewDialog or 
GetNewDialog with a pointer to the dialog storage (in the dStorage parameter) 


when you created the dialog. 


Note: Even if you didn't supply a pointer to the dialog storage, you may 
want to call CloseDialog if you created the dialog with NewDialog. 
You would call CloseDialog if you wanted to keep the item list around 
(since, unlike GetNewDialog, NewDialog does not use a copy of the 
item list). 


PROCEDURE DisposDialog (theDialog: DialogPtr); 
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DisposDialog calls CloseDialog (above) and then releases the memory occupied by 
the dialog's item list and dialog record. Call DisposDialog when you're done 
with a dialog if you let the dialog record be allocated in the heap when you 
created the dialog (by passing NIL as the dStorage parameter to NewDialog or 
GetNewDialog). 


PROCEDURE CouldDialog (dialogID: INTEGER); 


CouldDialog makes the dialog template having the given resource ID unpurgeable 
(reading it into memory if it's not already there). It does the same for the 
dialog window's definition function, the dialog's item list resource, and any 
items defined as resources. This is useful if the dialog box may come up when 
the resource file isn't accessible, such as during a disk copy. 


Warning: CouldDialog assumes your dialogs use the system font; if you've 
changed the font with SetDAFont, calling CouldDialog doesn't make 
the font unpurgeable. 


The CouldDialog procedure makes the dialog color table template unpurgeable 
(reading it into memory if it isn't already there), if it exists. It does the 
same for the dialog's color item list, if it has one. 


Warning: CouldDialog doesn't load or make 'FONT' or 'FOND' resources 
indicated in the color item list unpurgeable. 


PROCEDURE FreeDialog (dialogID: INTEGER); 


Given the resource ID of a dialog template previously specified in a call to 
CouldDialog, FreeDialog undoes the effect of CouldDialog (by making the 
resources purgeable). It should be called when there's no longer a need to keep 
the resources in memory. 


Given the resource ID of a dialog template previously specified in a call to 
CouldDialog, the FreeDialog routine undoes the effect of CouldDialog, by 
restoring the original purge state of the color table and color item list 
resources. 


Handling Dialog Events 
PROCEDURE ModalDialog (filterProc: ProcPtr; VAR itemHit: INTEGER); 


Call ModalDialog after creating a modal dialog and bringing up its window in the 
frontmost plane. ModalDialog repeatedly gets and handles events in the dialog's 
window; after handling an event involving an enabled dialog item, it returns 
with the item number in itemHit. Normally you'll then do whatever is appropriate 
as a response to an event in that item. 


ModalDialog gets each event by calling the Toolbox Event Manager function 
GetNextEvent. If the event is a mouse-down event outside the content region of 
the dialog window, ModalDialog emits sound number 1 (which should be a single 
beep) and gets the next event; otherwise, it filters and handles the event as 
described below. 
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Note: Once before getting each event, ModalDialog calls SystemTask, a 
Desk Manager procedure that must be called regularly so that desk 
accessories will work properly. 


The filterProc parameter determines how events are filtered. If it's NIL, the 
standard filterProc function is executed; this causes ModalDialog to return 1 in 
itemHit if the Return key or Enter key is pressed. If filterProc isn't NIL, 
ModalDialog filters events by executing the function it points to. Your 
filterProc function should have three parameters and return a Boolean value. For 
example, this is how it would be declared if it were named MyFilter: 


FUNCTION MyFilter (theDialog: DialogPtr; VAR theEvent: EventRecord; 
VAR itemHit: INTEGER) : BOOLEAN; 


A function result of FALSE tells ModalDialog to go ahead and handle the event, 
which either can be sent through unchanged or can be changed to simulate a 
different event. A function result of TRUE tells ModalDialog to return 
immediately rather than handle the event; in this case, the filterProc function 
sets itemHit to the item number that ModalDialog should return. 


Note: If you want it to be consistent with the standard filterProc function, 
your function should at least check whether the Return key or Enter 
key was pressed and, if so, return 1 in itemHit and a function result 
of TRUE. 


You can use the filterProc function, for example, to treat a typed character in 
a special way (such as ignore it, or make it have the same effect as another 
character or as clicking a button); in this case, the function would test for a 
key-down event with that character. As another example, suppose the dialog box 
contains a userItem whose procedure draws a clock with the current time 
displayed. The filterProc function can call that procedure and return FALSE 
without altering the current event. 


Note: ModalDialog calls GetNextEvent with a mask that excludes disk-inserted 
events. To receive disk-inserted events, your filterProc function can 
call GetNextEvent (or EventAvail) with a mask that accepts only that 
type of event. 


ModalDialog handles the events for which the filterProc function returns FALSE 
as follows: 


« In response to an activate or update event for the dialog window, 
ModalDialog activates or updates the window. 

e If the mouse button is pressed in an editText item, ModalDialog 
responds to the mouse activity as appropriate (displaying an insertion 
point or selecting text). If a key-down event occurs and there's an 
editText item, text entry and editing are handled in the standard way 
for such items (except that if the Command key is down, ModalDialog 
responds as though it's not). In either case, ModalDialog returns if 
the editText item is enabled or does nothing if it's disabled. If a 
key-down event occurs when there's no editText item, ModalDialog does 
nothing. 

e If the mouse button is pressed in a control, ModalDialog calls the 
Control Manager function TrackControl. If the mouse button is released 
inside the control and the control is enabled, ModalDialog returns; 
otherwise, it does nothing. 
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e If the mouse button is pressed in any other enabled item in the 
dialog box, ModalDialog returns. If the mouse button is pressed in 
any other disabled item or in no item, or if any other event occurs, 
ModalDialog does nothing. 


FUNCTION IsDialogEvent (theEvent: EventRecord) : BOOLEAN; 


If your application includes any modeless dialogs, call IsDialogEvent after 
calling the Toolbox Event Manager function GetNextEvent. 


Warning: If your modeless dialog contains any editText items, you must call 
IsDialogEvent (and then DialogSelect) even if GetNextEvent returns 
FALSE; otherwise your dialog won't receive null events and the 
caret won't blink. 


Pass the current event in theEvent. IsDialogEvent determines whether theEvent 
needs to be handled as part of a dialog. If theEvent is an activate or update 
event for a dialog window, a mouse-down event in the content region of an active 
dialog window, or any other type of event when a dialog window is active, 
IsDialogEvent returns TRUE; otherwise, it returns FALSE. 


When FALSE is returned, just handle the event yourself like any other event 
that's not dialog-related. When TRUE is returned, you'll generally end up 
passing the event to DialogSelect for it to handle (as described below), but 
first you should do some additional checking: 


¢ DialogSelect doesn't handle keyboard equivalents of commands. Check 
whether the event is a key-down event with the Command key held down 
and, if so, carry out the command if it's one that applies when a 
dialog window is active. (If the command doesn't so apply, do nothing.) 

e In special cases, you may want to bypass DialogSelect or do some 
preprocessing before calling it. If so, check for those events and 
respond accordingly. You would need to do this, for example, if the 
dialog is to respond to disk-inserted events. 


For cases other than these, pass the event to DialogSelect for it to handle. 


FUNCTION DialogSelect (theEvent: EventRecord; VAR theDialog: DialogPtr; 
VAR itemHit: INTEGER) : BOOLEAN; 


You'll normally call DialogSelect when IsDialogEvent returns TRUE, passing in 
theEvent an event that needs to be handled as part of a modeless dialog. 
DialogSelect handles the event as described below. If the event involves an 
enabled dialog item, DialogSelect returns a function result of TRUE with the 
dialog pointer in theDialog and the item number in itemHit; otherwise, it 
returns FALSE with theDialog and itemHit undefined. Normally when DialogSelect 
returns TRUE, you'll do whatever is appropriate as a response to the event, and 
when it returns FALSE you'll do nothing. 


If the event is an activate or update event for a dialog window, DialogSelect 
activates or updates the window and returns FALSE. 


If the event is a mouse-down event in an editText item, DialogSelect responds as 
appropriate (displaying a caret at the insertion point or selecting text). If 
it's a key-down or auto-key event and there's an editText item, text entry and 
editing are handled in the standard way. In either case, DialogSelect returns 
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TRUE if the editText item is enabled or FALSE if it's disabled. If a key-down or 
auto-key event is passed when there's no editText item, DialogSelect returns 
FALSE. 


Note: For a keyboard event, DialogSelect doesn't check to see whether the 
Command key is held down; to handle keyboard equivalents of commands, 
you have to check for them before calling DialogSelect. Similarly, to 
treat a typed character in a special way (such as ignore it, or make 
it have the same effect as another character or as clicking a button), 
you need to check for a key-down event with that character before 
calling DialogSelect. 


If the event is a mouse-down event in a control, DialogSelect calls the Control 
Manager function TrackControl. If the mouse button is released inside the 
control and the control is enabled, DialogSelect returns TRUE; otherwise, it 
returns FALSE. 


If the event is a mouse-down event in any other enabled item, DialogSelect 
returns TRUE. If it's a mouse-down event in any other disabled item or in no 
item, or if it's any other event, DialogSelect returns FALSE. 


Note: If the event isn't one that DialogSelect specifically checks for (if 
it's a null event, for example), and there's an editText item in the 
dialog, DialogSelect calls the TextEdit procedure TEIdle to make the 
caret blink. 
PROCEDURE DlgCut (theDialog: DialogPtr); [Not in ROM] 
DlgCut checks whether theDialog has any editText items and, if so, applies the 
TextEdit procedure TECut to the currently selected editText item. (If the dialog 
record's editField is 0 or greater, DlgCut passes the contents of the textH 


field to TECut.) You can call DlgCut to handle the editing command Cut when a 
modeless dialog window is active. 


Assembly-language note: Assembly-language programmers can just read the 
dialog record's fields and call TextEdit directly. 


PROCEDURE DlgCopy (theDialog: DialogPtr); [Not in ROM] 


DlgCopy is the same as DlgCut (above) except that it calls TECopy, for handling 
the Copy command. 


PROCEDURE DlgPaste (theDialog: DialogPtr); [Not in ROM] 


DlgPaste is the same as DlgCut (above) except that it calls TEPaste, for 
handling the Paste command. 


PROCEDURE DlgDelete (theDialog: DialogPtr); [Not in ROM] 


DlgDelete is the same as DlgCut (above) except that it calls TEDelete, for 
handling the Clear command. 


PROCEDURE DrawDialog (theDialog: DialogPtr); 


DrawDialog draws the contents of the given dialog box. Since DialogSelect and 
ModalDialog handle dialog window updating, this procedure is useful only in 
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unusual situations. You would call it, for example, to display a dialog box that 
doesn't require any response but merely tells the user what's going on during a 
time-consuming process. 


PROCEDURE UpdtDialog (theDialog: DialogPtr; updateRgn: RgnHandle); 


UpdtDialog is a faster version of the DrawDialog procedure. Instead of drawing 
the entire contents of the given dialog box, UpdtDialog draws only the items 
that are in a specified update region. UpdtDialog is called in response to an 
update event, and is usually bracketed by calls to the Window Manager procedures 
BeginUpdate and EndUpdate. UpdateRgn should be set to the visRgn of theWindow's 
port. (For more details, see the BeginUpdate procedure in the Window Manager 
chapter. ) 


Invoking Alerts 
FUNCTION Alert (alertID: INTEGER; filterProc: ProcPtr) : INTEGER; 


This function invokes the alert defined by the alert template that has the given 
resource ID. It calls the current sound procedure, if any, passing it the sound 
number specified in the alert template for this stage of the alert. If no alert 
box is to be drawn at this stage, Alert returns a function result of —1; 
otherwise, it creates and displays the alert window for this alert and draws the 
alert box. 


Warning: If the alert template resource can't be read, the function result 
is undefined. 


Note: Alert creates the alert window by calling NewDialog, and does the 
rest of its processing by calling ModalDialog. 


Alert repeatedly gets and handles events in the alert window until an enabled 
item is clicked, at which time it returns the item number. Normally you'll then 
do whatever is appropriate in response to a click of that item. 


Alert gets each event by calling the Toolbox Event Manager function 
GetNextEvent. If the event is a mouse-down event outside the content region of 
the alert window, Alert emits sound number 1 (which should be a single beep) and 
gets the next event; otherwise, it filters and handles the event as described 
below. 


The filterProc parameter has the same meaning as in ModalDialog (see above). If 
it's NIL, the standard filterProc function is executed, which makes the Return 
key or the Enter key have the same effect as clicking the default button. If you 
specify your own filterProc function and want to retain this feature, you must 
include it in your function. You can find out what the current default button is 
by looking at the aDefItem field of the dialog record for the alert 

(via the dialog pointer passed to the function). 


Alert handles the events for which the filterProc function returns FALSE as 
follows: 


« If the mouse button is pressed in a control, Alert calls the Control 
Manager procedure TrackControl. If the mouse button is released inside 
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the control and the control is enabled, Alert returns; otherwise, it 
does nothing. 

¢ If the mouse button is pressed in any other enabled item, Alert simply 
returns. If it's pressed in any other disabled item or in no item, or 
if any other event occurs, Alert does nothing. 


Before returning to the application with the item number, Alert removes the 
alert box from the screen. (It disposes of the alert window and its associated 
data structures, the item list, and the items.) 


Note: When an alert is removed, if it was overlapping the default button 
of a previous alert, that button's bold outline won't be redrawn. 


Note: The Alert function's removal of the alert box would not be the 
desired result if the user clicked a check box or radio button; 
however, normally alerts contain only static text, icons, pictures, 
and buttons that are supposed to make the alert box go away. If your 
alert contains other items besides these, consider whether it might 
be more appropriate as a dialog. 


The Alert function looks for a resource of type ‘actb' with the same ID as the 
alert. The alert color table is copied before it is passed to SetWinSize unless 
its ctSize field is equal to -—1, indicating that the default window colors are 
to be used instead. The copy is made so that the color table resource can be 
purged without affecting the alert. 


The color dialog item list resource is duplicated as well, so it can be 
purgeable. 


FUNCTION StopAlert (alertID: INTEGER; filterProc: ProcPtr) : INTEGER; 
StopAlert is the same as the Alert function (above) except that before drawing 
the items of the alert in the alert box, it draws the Stop icon in the top left 
corner of the box (within the rectangle (10,20) (42,52)). The Stop icon has the 
following resource ID: 

CONST stopIcon = 0; 

If the application's resource file doesn't include an icon with that ID number, 
the Dialog Manager uses the standard Stop icon in the system resource file (see 
Figure 11). 


The calls CautionAlert, StopAlert, and NoteAlert look for a resource of type 
‘actb' with the same ID as the alert. 


O Db A 


Bop Hote Caution 


Figure 11-Standard Alert Icons 
Figure 11-Standard Alert Icons 
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FUNCTION NoteAlert (alertID: INTEGER; filterProc: ProcPtr) : INTEGER; 


NoteAlert is like StopAlert except that it draws the Note icon, which has the 
following resource ID: 


CONST noteIcon = 1; 


The calls CautionAlert, StopAlert, and NoteAlert look for a resource of type 
‘actb' with the same ID as the alert. 


FUNCTION CautionAlert (alertID: INTEGER; filterProc: ProcPtr) : INTEGER; 


CautionAlert is like StopAlert except that it draws the Caution icon, which has 
the following resource ID: 


CONST cautionIcon = 2; 


The calls CautionAlert, StopAlert, and NoteAlert look for a resource of type 
‘actb' with the same ID as the alert. 


PROCEDURE CouldAlert (alertID: INTEGER); 


CouldAlert makes the alert template having the given resource ID unpurgeable 
(reading it into memory if it's not already there). It does the same for the 
alert window's definition function, the alert's item list resource, and any 
items defined as resources. This is useful if the alert may occur when the 
resource file isn't accessible, such as during a disk copy. 


Warning: Like CouldDialog, CouldAlert assumes your alerts use the system 
font; if you've changed the font with SetDAFont, calling CouldAlert 
doesn't make the font unpurgeable. 


The CouldAlert routine makes the alert color table template unpurgeable 
(reading it into memory if it isn't already there), if it exists. It does the 
same for the alert's color item list, if it has one. 


Warning: Like CouldDialog, CouldAlert doesn't load or make 'FONT' or 
'FOND' resources indicated in the color item list unpurgeable. 


PROCEDURE FreeAlert (alertID: INTEGER); 


Given the resource ID of an alert template previously specified in a call to 
CouldAlert, FreeAlert undoes the effect of CouldAlert (by making the resources 
purgeable). It should be called when there's no longer a need to keep the 
resources in memory. 


Given the resource ID of an alert template previously specified in a call to 
CouldAlert, the FreeAlert routine undoes the effect of CouldAlert, by restoring 
the original purge state of the color table and color item list resources. 


Manipulating Items in Dialogs and Alerts 


PROCEDURE ParamText (param0,paraml,param2,param3: Str255); 
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ParamText provides a means of substituting text in statText items: param 
through param3 will replace the special strings '*0' through '%3' in all 
statText items in all subsequent dialog or alert boxes. Pass empty strings for 
parameters not used. 


Assembly-language note: Assembly-language programmers may pass NIL for 
parameters not used or for strings that are not 
to be changed. 


For example, if the text is defined as ‘Cannot open document *@' and docName is 
a string variable containing a document name that the user typed, you can call 
ParamText(docName,' ',' ',' ') 


Note: All strings that may need to be translated to other languages should 
be stored in resource files. 


Assembly-language note: The Dialog Manager stores handles to the four 
ParamText parameters in a global array named DAStrings. 


PROCEDURE GetDItem (theDialog: DialogPtr; itemNo: INTEGER; 
VAR itemType: INTEGER; VAR item: Handle; VAR box: Rect); 


GetDItem returns in its VAR parameters the following information about the item 
numbered itemNo in the given dialog's item list: In the itemType parameter, the 
item type; in the item parameter, a handle to the item (or, for item type 
userItem, the procedure pointer); and in the box parameter, the display 
rectangle for the item. 


Suppose, for example, that you want to change the title of a control in a dialog 
box. You can get the item handle with GetDItem, coerce it to type ControlHandle, 
and call the Control Manager procedure SetCTitle to change the title. Similarly, 
to move the control or change its size, you would call MoveControl or 
SizeControl. 


Note: To access the text of a statText or editText item, you can pass the 
handle returned by GetDItem to GetIText or SetIText (see below). 


PROCEDURE SetDItem (theDialog: DialogPtr; itemNo: INTEGER; itemType: INTEGER; 
item: Handle; box: Rect); 


SetDItem sets the item numbered itemNo in the given dialog's item list, as 
specified by the parameters (without drawing the item). The itemType parameter 
is the item type; the item parameter is a handle to the item (or, for item type 
userItem, the procedure pointer); and the box parameter is the display rectangle 
for the item. 


Consider, for example, how to install an item of type userItem in a dialog: In 
the item list in the resource file, define an item in which the type is set to 
userItem and the display rectangle to (0,0)(0,0). Specify that the dialog window 
be invisible (in either the dialog template or the NewDialog call). After 
creating the dialog, coerce the item's procedure pointer to type Handle; then 
call SetDItem, passing that handle and the display rectangle for the item. 
Finally, call the Window Manager procedure ShowWindow to display the dialog 
window. 
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Note: Do not use SetDItem to change the text of a statText or editText item 
or to change or move a control. See the description of GetDItem above 
for more information. 


PROCEDURE HideDItem (theDialog: DialogPtr; itemNo: INTEGER); 


HideDItem hides the item numbered itemNo in the given dialog's item list by 
giving the item a display rectangle that's off the screen. (Specifically, if the 
left coordinate of the item's display rectangle is less than 8192, ShowDItem 
adds 16384 to both the left and right coordinates the rectangle.) If the item is 
already hidden (that is, if the left coordinate is greater than 8192), HideDItem 
does nothing. 


HideDItem calls the EraseRect procedure on the item's enclosing rectangle and 
adds the rectangle that contained the item (not necessarily the item's display 
rectangle) to the update region. If the specified item is an active editText 
item, the item is first deactivated (by calling TEDeactivate). 


Note: If you have items that are close to each other, be aware that the 
Dialog Manager draws outside of the enclosing rectangle by 3 pixels 
for editText items and by 4 pixels for a default button. 


An item that's been hidden by HideDItem can be redisplayed by the ShowDItem 
procedure. 


Note: To create a hidden item in a dialog item list, simply add 16384 to 
the left and right coordinates of the display rectangle. 


PROCEDURE ShowDItem (theDialog: DialogPtr; itemNo: INTEGER); 


ShowDItem redisplays the item numbered itemNo, previously hidden by HideDItem, 
by giving the item the display rectangle it had prior to the HideDItem call. 
(Specifically, if the left coordinate of the item's display rectangle is greater 
than 8192, ShowDItem subtracts 16384 from both the left and right coordinates 
the rectangle.) If the item is already visible (that is, if the left coordinate 
is less than 8192), ShowDItem does nothing. 


ShowDItem adds the rectangle that contained the item (not necessarily the 
item's display rectangle) to the update region so that it will be drawn. If the 
item becomes the only editText item, ShowDItem activates it (by calling 
TEActivate) . 


FUNCTION FindDItem (theDialog: DialogPtr; thePt: Point) : INTEGER; 

FindDItem returns the item number of the item containing the point specified, in 
local coordinates, by thePt. If the point doesn't lie within the item's 
rectangle, FindDItem returns —-1. If there are overlapping items, it returns the 
item number of the first item in the list containing the point. FindDItem is 
useful for changing the cursor when it's over a particular item. 

Note: FindDItem will return the item number of disabled items as well. 
PROCEDURE GetIText (item: Handle; VAR text: Str255); 


Given a handle to a statText or editText item in a dialog box, as returned by 
GetDItem, GetIText returns the text of the item in the text parameter. (If the 
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user typed more than 255 characters in an editText item, GetIText returns only 
the first 255.) 


PROCEDURE SetIText (item: Handle; text: Str255); 


Given a handle to a statText or editText item in a dialog box, as returned by 
GetDItem, SetIText sets the text of the item to the specified text and draws the 
item. For example, suppose the exact content of a dialog's text item cannot be 
determined until the application is running, but the display rectangle is 
defined in the resource file: Call GetDItem to get a handle to the item, and 
call SetIText with the desired text. 


PROCEDURE SelIText (theDialog: DialogPtr; itemNo: INTEGER; 
strtSel,endSel: INTEGER) 


Given a pointer to a dialog and the item number of an editText item in the 
dialog box, SelIText does the following: 


¢ If the item contains text, SelIText sets the selection range to extend 
from character position strtSel up to but not including character 
position endSel. The selection range is inverted unless strtSel equals 
endSel, in which case a blinking vertical bar is displayed to indicate 
an insertion point at that position. 

¢ If the item doesn't contain text, SelIText simply displays the insertion 
point. 


For example, if the user makes an unacceptable entry in the editText item, the 
application can put up an alert box reporting the problem and then select the 
entire text of the item so it can be replaced by a new entry. (Without this 
procedure, the user would have to select the item before making the new entry.) 


Note: You can select the entire texxt by specifying 0 for strtSel and 32767 
for endSel. For details about selection range and character position, 
see the TextEdit chapter. 


FUNCTION GetAlrtStage : INTEGER; [Not in ROM] 


GetAlrtStage returns the stage of the last occurrence of an alert, as a number 
from 0 to 3. 


Assembly-language note: Assembly-language programmers can get this number 
by accessing the global variable ACount. In addition, 
the global variable ANumber contains the resource ID 
of the alert template of the last alert that occurred. 


PROCEDURE ResetAlrtStage; [Not in ROM] 


ResetAlrtStage resets the stage of the last occurrence of an alert so that the 
next occurrence of that same alert will be treated as its first stage. This is 
useful, for example, when you've used ParamText to change the text of an alert 
such that from the user's point of view it's a different alert. 


Assembly-language note: Assembly-language programmers can set the global 
variable ACount to —1 for the same effect. 
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MODIFYING TEMPLATES IN MEMORY 


When you call GetNewDialog or one of the routines that invokes an alert, the 
Dialog Manager calls the Resource Manager to read the dialog or alert template 
from the resource file and return a handle to it. If the template is already in 
memory, the Resource Manager just returns a handle to it. If you want, you can 
call the Resource Manager yourself to read the template into memory (and make it 
unpurgeable), and then make changes to it before calling the dialog or alert 
routine. When called by the Dialog Manager, the Resource Manager will return a 
handle to the template as you modified it. 


To modify a template in memory, you need to know its exact structure and the 
data type of the handle through which it may be accessed. These are discussed 
below for dialogs and alerts. 


Dialog Templates in Memory 
The data structure of a dialog template is as follows: 


TYPE DialogTemplate = RECORD 


boundsRect: Rect; {becomes window's portRect} 
procID: INTEGER; {window definiton ID} 
visible: BOOLEAN; {TRUE if visible} 
fillerl: BOOLEAN; {not used} 
goAwayFlag: BOOLEAN; {TRUE if has go-away region} 
filler2: BOOLEAN; {not used} 
refCon: LONGINT; {window's reference value} 
itemsID: INTEGER; {resource ID of item list} 
title: Str255 {window's title} 

END; 


The fillerl and filler2 fields are there because for historical reasons the 
goAwayFlag and refCon fields have to begin on a word boundary. The itemsID field 
contains the resource ID of the dialog's item list. The other fields are the 
Same as the parameters of the same name in the NewDialog function; they provide 
information about the dialog window. 


You access the dialog template by converting the handle returned by the Resource 
Manager to a template handle: 


TYPE DialogTHndl 
DialogTPtr 


“DialogTPtr; 
“DialogTemplate; 


Alert Templates in Memory 
The data structure of an alert template is as follows: 


TYPE AlertTemplate = RECORD 
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boundsRect: Rect; {becomes window's portRect} 


itemsID: INTEGER; {resource ID of item list} 
stages: StageList {alert stage information} 
END; 


BoundsRect is the rectangle that becomes the portRect of the window's grafPort. 
The itemsID field contains the resource ID of the item list for the alert. 


The information in the stages field determines exactly what should happen at 
each stage of the alert. It's packed into a word that has the following 
structure: 


TYPE StageList = PACKED RECORD 


boldiItm4: 0..1; {default button item number minus 1} 
boxDrwn4: BOOLEAN; {TRUE if alert box to be drawn} 
sound4: 0..3 {sound number} 


boldItm3: 0..1; 
boxDrwn3: BOOLEAN; 
sound3: 0..3 
boldItm2: 0..1; 
boxDrwn2: BOOLEAN; 
sound2: 0..3 
boldItm1: 0..1; 
boxDrwnl: BOOLEAN; 
sound1: 0..3 
END; 


Notice that the information is stored in reverse order—for the fourth stage 
first, and for the first stage last. 


The boldItm field indicates which button should be the default button (and 
therefore boldly outlined in the alert box). If the first two items in the 
alert's item list are the OK button and the Cancel button, respectively, 0 will 
refer to the OK button and 1 to the Cancel button. The reason for this is that 
the value of boldItm plus 1 is interpreted as an item number, and normally items 
1 and 2 are the OK and Cancel buttons, respectively. Whatever the item having 
the corresponding item number happens to be, a bold rounded-corner rectangle 
will be drawn outside its display rectangle. 


Note: When deciding where to place items in an alert box, be sure to allow 
room for any bold outlines that may be drawn. 


The boxDrwn field is TRUE if the alert box is to be drawn. 


The sound field specifies which sound should be emitted at this stage of the 
alert, with a number from 0 to 3 that's passed to the current sound procedure. 
You can call ErrorSound to specify your own sound procedure; if you don't, the 
standard sound procedure will be used (as described earlier in the "Alerts" 
section). 


You access the alert template by converting the handle returned by the Resource 
Manager to a template handle: 


TYPE AlertTHndl 
AlertTPtr 


“AlertTPtr; 
“AlertTemplate; 
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Assembly-language note: Rather than offsets into the fields of the StageList 
data structure, there are masks for accessing the 
information stored for an alert stage in a stages 
word; they're listed in the summary at the end of 
this chapter. 
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FORMATS OF RESOURCES FOR DIALOGS AND ALERTS 


Every dialog template, alert template, and item list must be stored in a 
resource file, as must any icons or QuickDraw pictures in item lists and any 
control templates for items of type ctrlitemtresCtrl. The exact formats of a 
dialog template, alert template, and item list in a resource file are given 
below. For icons and pictures, the resource type is 'ICON' or 'PICT' and the 
resource data is simply the icon or the picture. The format of a control 
template is discussed in the Control Manager chapter. 


Dialog Templates in a Resource File 


The resource type for a dialog template is 'DLOG', and the resource data has the 
same format as a dialog template in memory. 


Number of bytes Contents 
8 bytes Same as boundsRect parameter to NewDialog 
2 bytes Same as procID parameter to NewDialog 
1 byte Same as visible parameter to NewDialog 
1 byte Ignored 
1 byte Same as goAwayFlag parameter to NewDialog 
1 byte Ignored 
4 bytes Same as refCon parameter to NewDialog 
2 bytes Resource ID of item list 
n bytes Same as title parameter to NewDialog 


(1-byte length in bytes, followed by the characters 
of the title) 


Alert Templates in a Resource File 


The resource type for an alert template is 'ALRT', and the resource data has the 
same format as an alert template in memory. 


Number of bytes Contents 
8 bytes Rectangle enclosing alert window 
2 bytes Resource ID of item list 
2 bytes Four stages 


The resource data ends with a word of information about stages. As shown in the 
example in Figure 12, there are four bits of stage information for each of the 
four stages, from the four low-order bits for the first stage to the four high- 
order bits for the fourth stage. Each set of four bits is as follows: 


Number of bits Contents 


1 bit Item number minus 1 of default button; normally 0 
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is OK and 1 is Cancel 
1 bit 1 if alert box is to be drawn, 0 if not 
2 bits Sound number (0 through 3) 


Note: So that the disk won't be accessed just for an alert that beeps, 
you may want to set the resPreload attribute of the alert's template 
in the resource file. For more information, see the Resource Manager 


chapter. 
Fourth stage third stage second stage first stage 
po;ififilofolifofofojofi 
eoee acm ye = = 
sound 3 sound 3 sound 2 sounl 1 
dra draur wo ww 
box box box box 
outline outline 
Cancel OR 


(value: hexadecimal F721) 


Figure 12-Sample Stages Word 
Figure 12—Sample Stages Word 


Item Lists in a Resource File 


The resource type for an item list is 'DITL'. The resource data has the 
following format: 


Number of bytes Contents 


2 bytes Number of items in list minus 1 
For each item: 
4 bytes 0 (placeholder for handle or procedure pointer) 
8 bytes Display rectangle (local coordinates) 
1 byte Item type 
1 byte Length of following data in bytes 
n bytes If item type is: Content is: 
(n is even) ctrlItem+resCtrl Resource ID (length 2) 


any other ctrlitem Title of the control 
statText, editText The text 

iconItem, picItem Resource ID (length 2) 
userItem Empty (length 0) 


As shown here, the first four bytes for each item serve as a placeholder for the 
item's handle or, for item type userItem, its procedure pointer; the handle or 
pointer is stored after the item list is read into memory. After the display 
rectangle and the item type, there's a byte that gives the length of the data 
that follows: For a text item, the data is the text itself; for an icon, 
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picture, or control of type ctrlitem+resCtrl, it's the two-byte resource ID for 
the item; and for any other type of control, it's the title of the control. For 
userItems, no data is specified. When the data is text or a control title, the 
number of bytes it occupies must be even to ensure word alignment of the next 
item. 


Note: The text in the item list can't be more than 240 characters long. 
Assembly-language note: Offsets into the fields of an item list are 


available as global constants; they're listed 
in the summary. 
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SUMMARY OF THE DIALOG MANAGER 


Constants 

CONST 
{ Item types } 
ctrlitem = 4; {add to following four constants} 
btnCtrl = 0; {standard button control} 
chkCtrl =". {standard check box control} 
radCtrl = 2: {standard radio button control} 
resCtrl = 3 {control defined in control template} 
statText = 8; {static text} 
editText = 16; {editable text (dialog only)} 
iconItem = 32; {icon} 
picItem = 64; {QuickDraw picture} 
userItem = 0; {application-defined item (dialog only) } 
itemDisable = 128; {add to any of above to disable} 


{ Item numbers of OK and Cancel buttons } 


ok 
cancel 


1; 
2; 


{ Resource IDs of alert icons } 


stopIcon = 0; 
noteIcon = 1; 
cautionIcon = 2; 


{ Constants for TextEdit and dialog boxes } 


TEdoFont = 1; {set font (family) number} 
TEdoFace = 2: {set character style} 
TEdoSize = 4; {set type size} 

TEdoColor = 8; {set foreground color} 
TEdoALlL = 15; {set all attributes} 
TEaddSize = 16; {adjust type size} 


{ Constants for dialog boxes only } 


doBColor = 8192; {set background color} 
doMode = 16384; {set txMode} 
doFontName = 32768; {set txFont from name} 
Data Types 
TYPE 
DialogPtr = WindowPtr; 
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DialogPeek = “DialogRecord; 
DialogRecord = RECORD 
window: WindowRecord; {dialog window} 
items: Handle; {item list} 
textH: TEHandle; {current editText item} 
editField: INTEGER; {editText item number minus 1} 
editOpen: INTEGER; {used internally} 
aDefitem: INTEGER {default button item number} 
END; 
DialogTHndl = “DialogTPtr; 
DialogTPtr = “DialogTemplate; 
DialogTemplate = RECORD 
boundsRect: Rect; {becomes window's portRect} 
procID: INTEGER; {window definiton ID} 
visible: BOOLEAN; {TRUE if visible} 
fillerl: BOOLEAN; {not used} 
goAwayFlag: BOOLEAN; {TRUE if has go-away region} 
filler2: BOOLEAN; {not used} 
refCon: LONGINT; {window's reference value} 
itemsID: INTEGER; {resource ID of item list} 
title: Str255 {window's title} 
END; 
AlertTHndl = “AlertTPtr; 
AlertTPtr = “AlertTemplate; 
AlertTemplate = RECORD 
boundsRect: Rect; {becomes window's portRect} 
itemsID: INTEGER; {resource ID of item list} 
stages: StageList {alert stage information} 
END; 
StageList = PACKED RECORD 
boldItm4: 0..1; {default button item number minus 1} 
boxDrwn4: BOOLEAN; {TRUE if alert box to be drawn} 
sound4: 0..3 {sound number} 
boldItm3: 0..1; 
boxDrwn3: BOOLEAN; 
sound3: 0..3 
boldItm2: 0..1; 
boxDrwn2: BOOLEAN; 
sound2: 0..3 
boldiItm1: 0..1; 
boxDrwnl: BOOLEAN; 
sound1: 0..3 
END; 
Routines 
Initialization 
PROCEDURE InitDialogs (resumeProc: ProcPtr); 
PROCEDURE ErrorSound (soundProc: ProcPtr); 
PROCEDURE SetDAFont (fontNum: INTEGER); [Not in ROM] 
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Creating and Disposing of Dialogs 


FUNCTION NewDialog (dStorage: Ptr; boundsRect: Rect; title: Str255; 
visible: BOOLEAN; procID: INTEGER; 
behind: WindowPtr; goAwayFlag: BOOLEAN; 
refCon: LONGINT; items: Handle) : DialogPtr; 
FUNCTION NewCDialog (dStorage: Ptr; boundsRect: Rect; title: Str255; 
visible: BOOLEAN; procID: INTEGER; 
behind: WindowPtr; goAwayFlag: BOOLEAN; 
refCon: LONGINT; items: Handle) : CDialogPtr; 
FUNCTION GetNewDialog (dialogID: INTEGER; dStorage: Ptr; 
behind: WindowPtr) : DialogPtr; 
PROCEDURE CloseDialog (theDialog: DialogPtr); 
PROCEDURE DisposDialog (theDialog: DialogPtr); 
PROCEDURE CouldDialog (dialogID: INTEGER); 
PROCEDURE FreeDialog (dialogID: INTEGER); 


Handling Dialog Events 


PROCEDURE ModalDialog (filterProc: ProcPtr; VAR itemHit: INTEGER); 

FUNCTION IsDialogEvent (theEvent: EventRecord) : BOOLEAN; 

FUNCTION DialogSelect (theEvent: EventRecord; VAR theDialog: DialogPtr; 
VAR itemHit: INTEGER) : BOOLEAN; 

PROCEDURE DlgCut (theDialog: DialogPtr); [Not in ROM] 

PROCEDURE DlgCopy (theDialog: DialogPtr); [Not in ROM] 

PROCEDURE DlgPaste (theDialog: DialogPtr); [Not in ROM] 

PROCEDURE DlgDelete (theDialog: DialogPtr); [Not in ROM] 

PROCEDURE DrawDialog (theDialog: DialogPtr); 

PROCEDURE UpdtDialog (theDialog: DialogPtr; updateRgn: RgnHandle); 


Invoking Alerts 


FUNCTION Alert 
FUNCTION StopAlert 
FUNCTION NoteAlert 
FUNCTION CautionAlert 
PROCEDURE CouldAlert 
PROCEDURE FreeAlert 


alertID: INTEGER; filterProc: ProcPtr) INTEGER; 
alertID: INTEGER; filterProc: ProcPtr) : INTEGER; 
alertID: INTEGER; filterProc: ProcPtr) : INTEGER; 
alertID: INTEGER; filterProc: ProcPtr) : INTEGER; 
alertID: INTEGER); 
alertID: INTEGER); 


aR ~~ 


Manipulating Items in Dialogs and Alerts 


PROCEDURE ParamText (param0,paraml,param2,param3: Str255); 
PROCEDURE GetDItem (theDialog: DialogPtr; itemNo: INTEGER; 
VAR itemType: INTEGER; VAR item: Handle; 
VAR box: Rect); 
PROCEDURE SetDItem (theDialog: DialogPtr; itemNo: INTEGER; 
itemType: INTEGER; item: Handle; box: Rect); 
PROCEDURE HideDItem (theDialog: DialogPtr; itemNo: INTEGER); 
PROCEDURE ShowDItem (theDialog: DialogPtr; itemNo: INTEGER); 
FUNCTION FindDItem (theDialog: DialogPtr; thePt: Point) : INTEGER; 
PROCEDURE GetIText (item: Handle; VAR text: Str255); 
PROCEDURE SetIText (item: Handle; text: Str255); 
PROCEDURE SelIText (theDialog: DialogPtr; itemNo: INTEGER; 
strtSel,endSel: INTEGER); 
FUNCTION GetAlrtStage : INTEGER; [Not in ROM] 
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PROCEDURE ResetALrtStage; [Not in ROM] 


UserItem Procedure 


PROCEDURE MyItem (theWindow: WindowPtr; itemNo: INTEGER); 


Sound Procedure 


PROCEDURE MySound (soundNo: INTEGER); 


FilterProc Function for Modal Dialogs and Alerts 


FUNCTION MyFilter (theDialog: DialogPtr; VAR theEvent: EventRecord; 
VAR itemHit: INTEGER) : BOOLEAN; 


Assembly-Language Information 


Constants 

; Item types 

ctrlitem .EQU 4 ;add to following four constants 
btnCtrl . EQU 0 ;standard button control 

chkCtrl . EQU 1 ;standard check box control 

radCtrl . EQU 2 ;standard radio button control 
resCtrl .EQU 3 ;control defined in control template 
statText .EQU 8 ;static text 

editText .EQU 16 ;editable text (dialog only) 
iconItem .EQU 32 ;icon 

picItem .EQU 64 ;QuickDraw picture 

userItem .EQU 0 ;application-defined item (dialog only) 
itemDisable .EQU 128 ;add to any of above to disable 


; Item numbers of OK and Cancel buttons 


okButton . EQU 1 
cancelButton . EQU 2 


» Resource IDs of alert icons 


stopIcon .EQU 0 
noteIcon . EQU 1 
cautionicon . EQU 2 


; Masks for stages word in alert template 


volBits . EQU 3 ssound number 
alBit . EQU 4 ‘whether to draw box 
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okDismissal . EQU 8 ‘item number of default button minus 1 


Dialog Record Data Structure 


dWindow Dialog window 

items Handle to dialog's item list 

teHandle Handle to current editText item 

editField Item number of editText item minus 1 (word) 
aDefitem Item number of default button (word) 
dWindLen Size in bytes of dialog record 


Dialog Template Data Structure 


dBounds Rectangle that becomes portRect of dialog window's 
grafPort (8 bytes) 

dWindProc Window definition ID (word) 

dVisible Nonzero if dialog window is visible (word) 

dGoAway Nonzero if dialog window has a go-away region (word) 

dRefCon Dialog window's reference value (long) 

dItems Resource ID of dialog's item list (word) 

dTitle Dialog window's title (preceded by length byte) 


Alert Template Data Structure 


aBounds Rectangle that becomes portRect of alert window's 
grafPort (8 bytes) 

aItems Resource ID of alert's item list (word) 

aStages Stages word; information for alert stages 


Item List Data Structure 


dlgMaxIndex Number of items minus 1 (word) 


itmHndlt Handle or procedure pointer for this item 

itmRect Display rectangle for this item (8 bytes) 

itmType Item type for this item (byte) 

itmData Length byte followed by data for this item 


(data must be even number of bytes) 
Variables 


ResumeProc Address of resume procedure 
DAStrings Handles to ParamText strings (16 bytes) 


DABeeper Address of current sound procedure 

DlgFont Font number for dialogs and alerts (word) 
ACount Stage number (0 through 3) of last alert (word) 
ANumber Resource ID of last alert (word) 
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Further Reference: 


Resource Manager 

QuickDraw 

Toolbox Event Manager 

Window Manager 

Control Manager 

TextEdit 

Technical Note #4, Error Returns from GetNewDialog 
Technical Note #5, Using Modeless Dialogs from Desk Accessories 
Technical Note #34, User Items in Dialogs 

Technical Note #95, How To Add Items to the Print Dialogs 
Technical Note #112, FindDItem 

Technical Note #203, Don't Abuse the Managers 

Technical Note #251, Safe cdevs 


END OF DOCUMENT 
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